<html>
<title>RARS 1.6 help contents
</title>
<body>
<center>
<h3>RARS - RISC-V Assembler and Runtime Simulator</h3>
<h4>Release 1.0</h4>
<h4>August 2017</h4>
<h4>Using RARS from a command line.</h4>
</center>

RARS can be run from a command interpreter to assemble and execute a program in
a batch fashion.
The format for running RARS from a command line is:<br><br>
<center><tt>java -jar rars.jar <i>[options]</i> program.asm <i>[more files...]</i> <i>[ </i>pa arg1<i> [more args...]]</i></tt></center>

<p>Items in <i>[ ]</i> are optional.  Valid options (not case sensitive, separated by spaces) are:<br><br>


<p>NOTICE: The table below is potentially innaccurate, if a command does not work as documented,
    file an issue at https://github.com/thethirdone/rars/issues, and check <tt>java -jar rars.jar h</tt>
    for potentially correct documentation</p>

<table border=1 cellpadding=3>
<tr><th>Option</th><th align="left">Description</th><th>Since</th></tr>
<tr><td width=40 align="right"><tt>a</tt></td><td>assemble only, do not simulate</td><td>1.0</td></tr>
<tr><td width=40 align="right"><tt>ae<i>n</i></tt></td><td>terminate RARS with integer exit code <i>n</i> if assembly error occurs</td><td>4.1</td></tr>
<tr><td width=40 align="right"><tt>ascii</tt></td><td>display memory or register contents interpreted as ASCII codes. (alternatives are <tt>dec</tt> and <tt>hex</tt>)</td><td>4.1</td></tr>
<tr><td width=40 align="right"><tt>b</tt></td><td>brief - do not display register/memory address along with contents</td><td>2.2</td></tr>
    <tr><td width=40 align="right"><tt>d</tt></td><td>display RARS debugging statements (of interest mainly to RARS developer)</td></tr>
<tr><td width=40 align="right"><tt>dec</tt></td><td>display memory or register contents in decimal. (alternatives are <tt>ascii</tt> and <tt>hex</tt>)</td><td>2.2</td></tr>
<tr><td width=40 align="right"><tt>dump</tt></td><td>dump memory contents to file.  
Option has 3 arguments, e.g. <tt>dump &lt;segment&gt; &lt;format&gt; &lt;file&gt;</tt>.  Current supported segments are <tt>.text</tt>
and <tt>.data</tt>.  Also supports an address range (see <i>m-n</i> below).  Current supported dump formats are <tt>Binary</tt>, <tt>HexText</tt>, <tt>BinaryText</tt>, <tt>AsciiText</tt>.  See examples below.</td><td>3.4</td></tr>
<tr><td width=40 align="right"><tt>g</tt></td><td>force GUI mode</td><td>1.6</td></tr>
<tr><td width=40 align="right"><tt>hex</tt></td><td>display memory or register contents in hexadecimal - this is the default. (alternatives are <tt>ascii</tt> and <tt>dec</tt>)</td><td>2.2</td></tr>
<tr><td width=40 align="right"><tt>h</tt></td><td>display this help.  Use this option by itself and with no filename.</td><td>1.0</td></tr>
<tr><td width=40 align="right"><tt>ic</tt></td><td>display instruction count; the number of basic instructions 'executed'</td><td>4.3</td></tr>
<tr><td width=40 align="right"><tt>mc</tt></td><td>set memory configuration.
Option has 1 argument, e.g. <tt>mc &lt;config&gt;</tt>.  Argument <tt>&lt;config&gt;</tt> is case-sensitive and its
possible values are <tt>Default</tt> for the default 32-bit address space, <tt>CompactDataAtZero</tt> for
a 32KB address space with data segment at address 0, or <tt>CompactTextAtZero</tt>
for a 32KB address space with text segment at address 0.</td><td>3.7</td></tr>
<tr><td width=40 align="right"><tt>me</tt></td><td>display RARS messages to standard err instead of standard out.  Allows you to separate RARS messages from program output using redirection.</td><td>4.3</td></tr>
<tr><td width=40 align="right"><tt>nc</tt></td><td>copyright notice will not be displayed.  Useful if redirecting or piping program output.</td><td>3.5</td></tr>
<tr><td width=40 align="right"><tt>np</tt></td><td>pseudo-instructions or extended instruction formats are not permitted.</td><td>3.0</td></tr>
<tr><td width=40 align="right"><tt>p</tt></td><td>project option - will assemble the specified file and all other assembly files (*.asm; *.s) in its directory.</td><td>3.1</td></tr>
<tr><td width=40 align="right"><tt>se<i>n</i></tt></td><td>terminate RARS with exit code <i>n</i> if simulate (run) error occurs</td><td>4.1</td></tr>
<tr><td width=40 align="right"><tt>sm</tt></td><td>start execution at statement having global label 'main' if defined</td><td>3.8</td></tr>
<tr><td width=40 align="right"><tt>smc</tt></td><td>Self Modifying Code - Program can write and execute in either text or data segment</td><td>4.4</td></tr>
<tr><td width=40 align="right"><tt>we</tt></td><td>assembler warnings will be considered errors.</td><td>3.5</td></tr>
<tr><td width=40 align="right"><i>n</i></td><td>where <i>n</i> is an integer maximum count of execution steps to simulate.
                  If 0, negative or not specified, there is no maximum.</td><td>1.0</td></tr>
<tr><td width=40 align="right"><tt>$</tt><i>reg</i></td><td>where <i>reg</i> is number or name (e.g. 5, t3, f10) of register whose 
                  content to display at end of run.  Even-numbered float register displays both float and double.  Option may be repeated.
				  <em>NOTE: Depending on your command shell, you may need to escape the $, e.g. <tt>\$t3</tt></em></td><td>2.2</td></tr>
<tr><td width=40 align="right"><i>reg_name</i></td><td>where <i>reg_name</i> is the name (e.g. t3, f10) of register whose 
                  content to display at end of run.  Even-numbered float register displays both float and double.  Option may be repeated. $ not required.</td><td>2.2</td></tr>
<tr><td width=40 align="right"><i>m</i>-<i>n</i></td><td>memory address range from <i>m</i> to <i>n</i> whose contents to
                  display at end of run. <i>m</i> and <i>n</i> may be decimal or hexadecimal (starts with <tt>0x</tt>),
                  <i>m</i> &lt;= <i>n</i>, both must be on word boundary.  Option may be repeated.</td><td>2.2</td></tr>
<tr><td width=40 align="right"><tt>pa</tt></td><td>program arguments - all remaining space-separated items are argument values provided to the
program via $a0 (argc - argument count) and $a1 (argv - address of array containing pointers to null-terminated argument
strings). The count is also at the top of the runtime stack ($sp), followed by the array.<i>This option and its arguments must be the last items in the command!</i></td><td>3.5</td></tr>
</table>

<p><b>Example: </b><tt>java -jar rars.jar h</tt> <br>
Displays command options and explanations.
<p><b>Example: </b><tt>java -jar rars.jar $s0 $s1 0x10010000-0x10010010 fibonacci.asm</tt> <br>
Assemble and run <tt>fibonacci.asm</tt>.  At the end of the run, display the contents of registers <tt>$s0</tt> and
<tt>$s1</tt>, and the contents of memory locations 0x10010000 through 0x10010010.  The contents are displayed in
hexadecimal format.
<p><b>Example: </b><tt>java -jar rars.jar a fibonacci.asm</tt><br>
Assemble <tt>fibonacci.asm</tt>.  Does not attempt to run the program, and the assembled code is not saved.
<p><b>Example: </b><tt>java -jar rars.jar 100000 infinite.asm</tt><br>
Assemble and run <tt>infinite.asm</tt> for a maximum of 100,000 execution steps.
<p><b>Example: </b><tt>java -jar rars.jar p major.asm</tt><br>
Assemble <tt>major.asm</tt> and all other files in the same directory, link the assembled code, and run starting with the first instruction in <tt>major.asm</tt>.
<p><b>Example: </b><tt>java -jar rars.jar  major.asm  minor.asm  sub.asm</tt><br>
Assemble and link <tt>major.asm</tt>, <tt>minor.asm</tt> and <tt>sub.asm</tt>.  If successful, execution
will begin with the first instruction in <tt>major.asm</tt>.
<p><b>Example: </b><tt>java -jar rars.jar a dump .text HexText hexcode.txt fibonacci.asm</tt><br>
Assemble <tt>fibonacci.asm</tt> without simulating (note use of 'a' option).  At end of assembly, dump the text segment (machine code) to
file <tt>hexcode.txt</tt> in hexadecimal text format with one instruction per line.
<p><b>Example: </b><tt>java -jar rars.jar  dump 0x10010000-0x10010020 HexText hexcode.txt fibonacci.asm</tt><br>
Assemble and simulate <tt>fibonacci.asm</tt>.  At end of simulation, dump the contents of addresses 0x1001000 to
0x10010020 to file <tt>hexdata.txt</tt> in hexadecimal text format with one word per line.
<p><b>Example: </b><tt>java -jar rars.jar t0 process.asm  pa counter 10</tt><br>
Assemble and run <tt>process.asm</tt> with two program argument values, "counter" and "10".  It may retrieve the
argument count (2) from <tt>$a0</tt>, and the address of an array containing pointers to the strings "count" and "10",
from <tt>$a1</tt>.  At the
end of the run, display the contents of register <tt>$t0</tt>.


<p>The ability to run RARS from the command line is useful if you want to develop
scripts (macros) to exercise a given program under multiple scenarios
or if you want to run a number of different programs
such as for grading purposes.
</body>
</html>